<!doctype html>
<html class="default no-js">
<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<title>Amazon DynamoDB DataMapper For JavaScript</title>
	<meta name="description" content="">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
	<div class="tsd-page-toolbar">
		<div class="container">
			<div class="table-wrap">
				<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
					<div class="field">
						<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
						<input id="tsd-search-field" type="text" />
					</div>
					<ul class="results">
						<li class="state loading">Preparing search index...</li>
						<li class="state failure">The search index is not available</li>
					</ul>
					<a href="index.html" class="title">Amazon DynamoDB DataMapper For JavaScript</a>
				</div>
				<div class="table-cell" id="tsd-widgets">
					<div id="tsd-filter">
						<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
						<div class="tsd-filter-group">
							<div class="tsd-select" id="tsd-filter-visibility">
								<span class="tsd-select-label">All</span>
								<ul class="tsd-select-list">
									<li data-value="public">Public</li>
									<li data-value="protected">Public/Protected</li>
									<li data-value="private" class="selected">All</li>
								</ul>
							</div>
							<input type="checkbox" id="tsd-filter-inherited" checked />
							<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
							<input type="checkbox" id="tsd-filter-externals" checked />
							<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
						</div>
					</div>
					<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
				</div>
			</div>
		</div>
	</div>
	<div class="tsd-page-title">
		<div class="container">
			<ul class="tsd-breadcrumb">
				<li>
					<a href="globals.html">Globals</a>
				</li>
			</ul>
			<h1> Amazon DynamoDB DataMapper For JavaScript</h1>
		</div>
	</div>
</header>
<div class="container container-main">
	<div class="row">
		<div class="col-8 col-content">
			<div class="tsd-panel tsd-typography">
				<h1 id="amazon-dynamodb-datamapper-for-javascript">Amazon DynamoDB DataMapper For JavaScript</h1>
				<p><a href="http://aws.amazon.com/apache-2-0/"><img src="https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat" alt="Apache 2 License"></a></p>
				<p>This repository hosts several packages that collectively make up an object to
				document mapper for JavaScript applications using Amazon DynamoDB.</p>
				<h2 id="getting-started">Getting started</h2>
				<p><a href="packages/dynamodb-data-mapper">The <code>@aws/dynamodb-data-mapper</code> package</a> provides
					a simple way to persist and load an application&#39;s domain objects to and from
					Amazon DynamoDB. When used together with the decorators provided by <a href="packages/dynamodb-data-mapper-annotations">the
					<code>@aws/dynamodb-data-mapper-annotations</code> package</a>,
					you can describe the relationship between a class and its representation in
				DynamoDB by adding a few decorators:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {
    attribute,
    hashKey,
    rangeKey,
    table,
} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-data-mapper-annotations'</span>;

<span class="hljs-meta">@table</span>(<span class="hljs-string">'table_name'</span>)
<span class="hljs-keyword">class</span> MyDomainObject {
    <span class="hljs-meta">@hashKey</span>()
    id: <span class="hljs-built_in">string</span>;

    <span class="hljs-meta">@rangeKey</span>({defaultProvider: <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>()})
    createdAt: <span class="hljs-built_in">Date</span>;

    <span class="hljs-meta">@attribute</span>()
    completed?: <span class="hljs-built_in">boolean</span>;
}
</code></pre>
				<p>With domain classes defined, you can interact with records in DynamoDB via an
				instance of <code>DataMapper</code>:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {DataMapper} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-data-mapper'</span>;
<span class="hljs-keyword">import</span> DynamoDB = <span class="hljs-built_in">require</span>(<span class="hljs-string">'aws-sdk/clients/dynamodb'</span>);

<span class="hljs-keyword">const</span> mapper = <span class="hljs-keyword">new</span> DataMapper({
    client: <span class="hljs-keyword">new</span> DynamoDB({region: <span class="hljs-string">'us-west-2'</span>}), <span class="hljs-comment">// the SDK client used to execute operations</span>
    tableNamePrefix: <span class="hljs-string">'dev_'</span> <span class="hljs-comment">// optionally, you can provide a table prefix to keep your dev and prod tables separate</span>
});
</code></pre>
				<h3 id="supported-operations">Supported operations</h3>
				<p>Using the <code>mapper</code> object and <code>MyDomainObject</code> class defined above, you can
				perform the following operations:</p>
				<h4 id="put"><code>put</code></h4>
				<p>Creates (or overwrites) an item in the table</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">const</span> toSave = <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'foo'</span>});
mapper.put(toSave).then(<span class="hljs-function"><span class="hljs-params">objectSaved</span> =&gt;</span> {
    <span class="hljs-comment">// the record has been saved</span>
});
</code></pre>
				<h4 id="get"><code>get</code></h4>
				<p>Retrieves an item from DynamoDB</p>
				<pre><code class="lang-typescript">mapper.get(<span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'foo'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800000</span>)}))
    .then(<span class="hljs-function"><span class="hljs-params">myItem</span> =&gt;</span> {
        <span class="hljs-comment">// the item was found</span>
    })
    .catch(<span class="hljs-function"><span class="hljs-params">err</span> =&gt;</span> {
        <span class="hljs-comment">// the item was not found</span>
    })
</code></pre>
				<p><strong>NB:</strong> The promise returned by the mapper will be rejected with an
				<code>ItemNotFoundException</code> if the item sought is not found.</p>
				<h4 id="update"><code>update</code></h4>
				<p>Updates an item in the table</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">const</span> myItem = <span class="hljs-keyword">await</span> mapper.get(<span class="hljs-built_in">Object</span>.assign(
    <span class="hljs-keyword">new</span> MyDomainObject,
    {id: <span class="hljs-string">'foo'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800000</span>)}
));
myItem.completed = <span class="hljs-literal">true</span>;

<span class="hljs-keyword">await</span> mapper.update(myItem);
</code></pre>
				<h4 id="delete"><code>delete</code></h4>
				<p>Removes an item from the table</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">await</span> mapper.delete(<span class="hljs-built_in">Object</span>.assign(
    <span class="hljs-keyword">new</span> MyDomainObject,
    {id: <span class="hljs-string">'foo'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800000</span>)}
));
</code></pre>
				<h4 id="scan"><code>scan</code></h4>
				<p>Lists the items in a table or index</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> item of mapper.scan(MyDomainObject)) {
    <span class="hljs-comment">// individual items will be yielded as the scan is performed</span>
}

<span class="hljs-comment">// Optionally, scan an index instead of the table:</span>
<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> item of mapper.scan(MyDomainObject, {indexName: <span class="hljs-string">'myIndex'</span>})) {
    <span class="hljs-comment">// individual items will be yielded as the scan is performed</span>
}
</code></pre>
				<h4 id="query"><code>query</code></h4>
				<p>Finds a specific item (or range of items) in a table or index</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> foo of mapper.query(MyDomainObject, {id: <span class="hljs-string">'foo'</span>})) {
    <span class="hljs-comment">// individual items with a hash key of "foo" will be yielded as the query is performed</span>
}
</code></pre>
				<h4 id="batch-operations">Batch operations</h4>
				<p>The mapper also supports batch operations. Under the hood, the batch will
					automatically be split into chunks that fall within DynamoDB&#39;s limits (25 for
					<code>batchPut</code> and <code>batchDelete</code>, 100 for <code>batchGet</code>). The items can belong to any
					number of tables, and exponential backoff for unprocessed items is handled
				automatically.</p>
				<h5 id="batchput"><code>batchPut</code></h5>
				<p>Creates (or overwrites) multiple items in the table</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">const</span> toSave = [
    <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'foo'</span>, completed: <span class="hljs-literal">false</span>}),
    <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'bar'</span>, completed: <span class="hljs-literal">false</span>})
];
<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> persisted of mapper.batchPut(toSave)) {
    <span class="hljs-comment">// items will be yielded as they are successfully written</span>
}
</code></pre>
				<h5 id="batchget"><code>batchGet</code></h5>
				<p>Fetches multiple items from the table</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">const</span> toGet = [
    <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'foo'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800000</span>)}),
    <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'bar'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800001</span>)})
];
<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> found of mapper.batchGet(toGet)) {
    <span class="hljs-comment">// items will be yielded as they are successfully retrieved</span>
}
</code></pre>
				<p><strong>NB:</strong> Only items that exist in the table will be retrieved. If a key is not
				found, it will be omitted from the result.</p>
				<h5 id="batchdelete"><code>batchDelete</code></h5>
				<p>Removes multiple items from the table</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">const</span> toRemove = [
    <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'foo'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800000</span>)}),
    <span class="hljs-built_in">Object</span>.assign(<span class="hljs-keyword">new</span> MyDomainObject, {id: <span class="hljs-string">'bar'</span>, createdAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>(<span class="hljs-number">946684800001</span>)})
];
<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> found of mapper.batchDelete(toRemove)) {
    <span class="hljs-comment">// items will be yielded as they are successfully removed</span>
}
</code></pre>
				<h4 id="table-lifecycle-operations">Table lifecycle operations</h4>
				<h5 id="createtable"><code>createTable</code></h5>
				<p>Creates a table for the mapped class and waits for it to be initialized:</p>
				<pre><code class="lang-typescript">mapper.createTable(MyDomainObject, {readCapacityUnits: <span class="hljs-number">5</span>, writeCapacityUnits: <span class="hljs-number">5</span>})
    .then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
        <span class="hljs-comment">// the table has been provisioned and is ready for use!</span>
    })
</code></pre>
				<h5 id="ensuretableexists"><code>ensureTableExists</code></h5>
				<p>Like <code>createTable</code>, but only creates the table if it doesn&#39;t already exist:</p>
				<pre><code class="lang-typescript">mapper.ensureTableExists(MyDomainObject, {readCapacityUnits: <span class="hljs-number">5</span>, writeCapacityUnits: <span class="hljs-number">5</span>})
    .then(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
        <span class="hljs-comment">// the table has been provisioned and is ready for use!</span>
    })
</code></pre>
				<h5 id="deletetable"><code>deleteTable</code></h5>
				<p>Deletes the table for the mapped class and waits for it to be removed:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">await</span> mapper.deleteTable(MyDomainObject)
</code></pre>
				<h5 id="ensuretablenoexists"><code>ensureTableNoExists</code></h5>
				<p>Like <code>deleteTable</code>, but only deletes the table if it exists:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">await</span> mapper.ensureTableNotExists(MyDomainObject)
</code></pre>
				<h2 id="constituent-packages">Constituent packages</h2>
				<p>The DataMapper is developed as a monorepo using <a href="https://github.com/lerna/lerna"><code>lerna</code></a>.
					More detailed documentation about the mapper&#39;s constituent packages is available
				by viewing those packages directly.</p>
				<ul>
					<li><a href="packages/dynamodb-auto-marshaller/">Amazon DynamoDB Automarshaller</a></li>
					<li><a href="packages/dynamodb-batch-iterator/">Amazon DynamoDB Batch Iterator</a></li>
					<li><a href="packages/dynamodb-data-mapper/">Amazon DynamoDB DataMapper</a></li>
					<li><a href="packages/dynamodb-data-mapper-annotations/">Amazon DynamoDB DataMapper Annotations</a></li>
					<li><a href="packages/dynamodb-data-marshaller/">Amazon DynamoDB Data Marshaller</a></li>
					<li><a href="packages/dynamodb-expressions/">Amazon DynamoDB Expressions</a></li>
					<li><a href="packages/dynamodb-query-iterator/">Amazon DynamoDB Query Iterator</a></li>
				</ul>
			</div>
		</div>
		<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
			<nav class="tsd-navigation primary">
				<ul>
					<li class="globals  ">
						<a href="globals.html"><em>Globals</em></a>
					</li>
				</ul>
			</nav>
			<nav class="tsd-navigation secondary menu-sticky">
				<ul class="before-current">
				</ul>
			</nav>
		</div>
	</div>
</div>
<footer>
	<div class="container">
		<h2>Legend</h2>
		<div class="tsd-legend-group">
			<ul class="tsd-legend">
				<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
				<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
				<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
				<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
				<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
				<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
				<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
				<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
				<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
				<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
				<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
				<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
			</ul>
		</div>
	</div>
</footer>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>